Creating a guide

Every user guide needs to be registered with the Guide Viewer for it to display. This can be done in two ways:

  1. Creating a stand-alone "guide addon".
    1. If you have written addons before, just skip the basics here :)
    2. Create a new directory under \Interface\Addons, naming it - for example - MyGuide.
    3. Create a file in there, naming it MyGuide.toc, containing - basically - this: ## Interface: 30300
      ## Title: My Guide For Something
      ## Dependencies: ZygorGuidesViewer

      MyGuide.lua
    4. Create another file, name it MyGuide.lua, and paste this into it:
      ZygorGuidesViewer:RegisterGuide("My Leet Guides\\My First Guide",[[
      	author me@myself.com
      	step
      		Do some very secret unspecified something :)
      	step
      		Keep playing...
      ]])
      		
    5. Edit this to your likings.
    6. Start WoW, open the ZygorGuidesViewer window, hover at the title and click the guide selection button - your guide should be visible in the drop-down list.

    Now all you need is keep writing the guide, and reloading the game's UI to reload the guide.

    This method is by far the easiest and best way to create and distribute your guides - it has one major drawback, however. According to Blizzard's policies, you are not allowed to sell addons of any kind. Distribution of a commercial guide in this form could probably be considered violating their terms. Stay safe.

  2. Including data in the addon's folder
    1. Prepare a guide according to the syntax described above and below.
    2. Save it as Guide01.lua (through Guide40.lua) in the ZygorGuidesViewer\Guides folder.
    3. Re-launch the game. Your guides should be available for selection.

Guide format

A guide consists of a series of steps, being displayed one at a time, often having step options assigned.
Each step may contain up to 20 lines, consisting of various tags separated with a pipe character (|).
Additionally, some global options may be set.

Spaces/tabs at beginnings and ends of lines are ignored. Whole empty lines are ignored as well. You can include comments, starting with // until the end of line (C-style).

The resulting structure looks like this:

global option
global option
step  // comment
  step option
  step option
  tag|tag|tag
  tag|tag|tag
step
  step option
  step option
  tag|tag|tag
  tag|tag|tag

Global options:

defaultfor race
Makes this guide loaded by default when starting a character of a specific race. Death Knights are considered a race, for convenience. Examples: defaultfor Human, defaultfor DeathKnight.
author email, name...
Sets the author's credentials. Used in generated bug reports.
description text
Sets the description used in the guide's details in the addon's main settings screen.
startlevel level
Use this level as default for the first steps of the guide. Steps use levels to determine what's obsolete; set to 80 to never obsolete your steps.
next guide title
Designates guide title to follow this guide. Note: full title needed, multi-folder path and all.
daily
Marks the guide as a "dailies" guide, enabling periodic resetting of daily-marked quests.
type typename
Explicitly specifies typename to be the type of the guide. Example values are: leveling, daily, loremaster, macro, event. The type might be guessed implicitly from the other global options or the name of the guide.
class classname
Marks the guide to be only valid for characters of classname class. The classname is specified in English "system" notation with capitalized letters without spaces. This also sets the icon for the guide to be that of the class.
spec specname
Marks the guide to be only valid for characters of specname spec. Invalid without class option. The specname is specified in English. This also sets the icon for the guide to be that of the corresponding talent tree. This option may be specified several times. If two or more specs are requested, the icon resets to that of the class option.
icon path [x₁,x₂,y₁,y₂]
Specifies the icon displayed for the guide. The path denotes the WoW texture used for the icon, while x₁,x₂,y₁,y₂ are optional texture coordinates which are thought to be {0,1,0,1} if omitted. This option overrides icons specified in both class and spec options.

Macro-only options:

Theese options are only specified for a macro-typed guides. Whenever the parser encounters one of them, the guide is marked as a macro guide and the steps are not parsed.

macroname name
Specifies the name of the macro to be ZM_name. Because of the way the macro search works in WoW API this should be unique within all the guides loaded and the user's own Macros database. Failure to do so might lead to unexpected behaviour. Whenever the Guide Viewer is loaded it repopulates the macros with known names which serves for both automatical update and localization.
macroicon path
Designates the path to be a WoW texture used for the macro display in Macro Panel and the Actionbar. Since 4.3.0 WoW no longer uses the integer indexation of macro icons, therefore virtually any texture can be used. Consistently to the ingame Macro Panel, the "INTERFACE\ICONS\" part is stripped. If the option is not specified, the default "question mark" texture is used, corresponding path is being "INV_MISC_QUESTIONMARK".
macrotext
Marks the end of global options of macro-typed guides. After this line the rest of the guide text is thought to be directly the code of the macro. The extra whitespace is wiped out, while the newlines are preserved. Example general view of a macro guide: description Tries to cast Backstab or Ambush but even if it fails starts the attack either way
author support@zygorguides.com
class ROGUE
spec Subtlety
spec Assassination
macroname Backstab
macrotext
#showtooltip
/startattack [nostealth]
/cast [nostealth] ##53; ##8676
The ##id is used for spells and items, whereas id corresponds to the game identifier of a spell or an item. Ideally, you would want to use the numeric notation, but directly writing the names in text also works. The numerics give the localization benefit: upon startup they are expanded into localized text strings which allows to use the same macro across different client locales and are quite useful when you intend to change the game locale alot without the need to rewrite your macros each time. Keep in mind that the names might be of different length across the locales, therefore some long macros might work nice in one locale but fail to compile in another where the expansion of the names exceeds the 256 symbol limit.

Steps:

Each step starts with a step word, alone in a line. This marker is followed by step options and lines.

Step options:

These pertain to one step, setting its properties.

Option Description Example
map name Sets a default map for this (and subsequent) step's waypoints. Use it if you prefer your waypoint markers to have only coordinates. map Elwynn Forest
level level Indicates that the step should be completed at level level. Optional. If no level is set for a step, the previous step's level is used, or the guide's startlevel setting. Note: the ding tag sets the level as well. level 12
title text Sets the title of the waypoint pertaining to the step. May be overridden by a line-specific title tag. Optional. title Entrance to the mine
only race/class... Designates the step as being valid only for a specific race/class.
Any combination of races/classes, separated with commas. A race starting with ! means 'NOT'. As the races are OR-ed together, multiple NOTs don't make sense.
Note: the last line in the example restricts the step to Gnomes of any class, Dwarven Paladins, and Mages of any race - not to Gnomish-or-Dwarven Paladins-or-Mages.
only Human Warrior
only Warrior,Priest,Warlock
only !Human
only Gnome,Dwarf Paladin,Mage
only if condition Sets a raw scripted condition for the step's availability.
Condition is a simple Lua expression. Available shorthands:
  • rep("Faction") -- returns standing with a faction (locale-safe). Compare using >,<,==,>=,<=,~= with one of the predefined values named after standings: Neutral,Honored,Exalted... Case-sensitive.
  • skill("Profession") -- returns skill in profession.
  • any other Lua expression -- evaluates and if it returns non-nil, the step is available.
only Human Warrior
only if rep("Stormwind")==Exalted
only if skill('Herbalism')>0
only if UnitName("player")=="Tinkywinky"

Step lines:

Completable lines. Each step line is intended to either require the player to perform some action, or just provide advice. If a line contains one of the "completable" tags, it becomes a completable line. A line containing only "descriptive" actions or tags, or forced into incompletability (using the |n tag), will just be displayed for the player to read.

Completion condition. The first completable tag on a line decides its completion condition. Other tags in the line can only enhance the completable tag's behaviour. Or, they can make no sense at all. Tags are separated using the '|' pipe character. Example:
'Hearth to Ironforge|goto Ironforge,12.3,45.6|use Hearthstone##6948|noway This would read as: "Display a descriptive instruction; then, use goto completion upon reaching Ironforge; add a usable item icon with Hearthstone on it; finally, make this line not show a waypoint arrow.

Waypoints. A goto tag, or a ' ("text") tag with a coordinate pair in its contents, will automatically create a mapnote and a waypoint for it. The mapnote's title can be set using the title step option, or individually for the line using the title line tag. A line with coordinates can be clicked to force a waypoint to this location to be displayed.

Indentation. Step lines can be prepended with multiple '.'s (periods) to indent them visually. Example: goto 12,34
.talk Mountain King
..accept Into the Hall
Result: Go to 12,34
   Talk to Mountain King
      Accept `Into the Hall'

Tags

Simple actions:

Clickable icons:

Modifiers:

Other tags:

Advanced examples: ' Kill Smelly Joe that wanders around|kill Smelly Joe kill Smelly Joe|' Kill Smelly Joe that wanders around kill Smelly Joe|Kill Smelly Joe that wanders around Kill Smelly Joe that wanders around Create a descriptive line that completes upon killing a mob. All are equivalent - the third line as well, as „Kill” (capitalized) is not a valid tag, and thus is treated as „text”, again overriding normal display for the kill command. ' Go outside of the house|goto 34.5,12.8,0.1|c Go outside of the house (has waypoint) A descriptive, completeable, „go to” line with a precise destination. ' Climb to 12.8,34.3|c A descriptive, completeable, „go to” line with a precise destination. goto Elwynn Forest,12.3,45.6|c kill 6 Stalker 'Chop 5 trees|goal 5 Trees chopped|goto 22,34 only Draenei Warrior,Human Paladin Just a bunch of different options.